<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Clipboard toolkit &mdash; Dragonfly v0.6.4rc3 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '0.6.4rc3',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Dragonfly v0.6.4rc3 documentation" href="index.html" />
    <link rel="up" title="Windows sub-package" href="windows.html" />
    <link rel="next" title="Miscellaneous" href="misc.html" />
    <link rel="prev" title="Windows sub-package" href="windows.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="misc.html" title="Miscellaneous"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="windows.html" title="Windows sub-package"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Dragonfly v0.6.4rc3 documentation</a> &raquo;</li>
          <li><a href="windows.html" accesskey="U">Windows sub-package</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="clipboard-toolkit">
<span id="refclipboard"></span><h1>Clipboard toolkit<a class="headerlink" href="#clipboard-toolkit" title="Permalink to this headline">¶</a></h1>
<p>Dragonfly&#8217;s clipboard toolkit offers easy access to and manipulation of
the Windows system clipboard.  The
<a title="dragonfly.windows.clipboard.Clipboard" class="reference internal" href="#dragonfly.windows.clipboard.Clipboard"><tt class="xref docutils literal"><span class="pre">dragonfly.windows.clipboard.Clipboard</span></tt></a> class forms the core of
this toolkit.  Each instance of this class is a container with a structure
similar to the Windows system clipboard, mapping content formats to
content data.</p>
<div class="section" id="usage-examples">
<h2>Usage examples<a class="headerlink" href="#usage-examples" title="Permalink to this headline">¶</a></h2>
<p>An instance of something contains clipboard data.  The data stored within
an instance can be transferred to and from the Windows system clipboard as
follows: (before running this example, the text &#8220;asdf&#8221; was copied into the
Windows system clipboard)</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">dragonfly.windows.clipboard</span> <span class="kn">import</span> <span class="n">Clipboard</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">instance</span> <span class="o">=</span> <span class="n">Clipboard</span><span class="p">()</span>        <span class="c"># Create empty instance.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">instance</span>
<span class="go">Clipboard()</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">instance</span><span class="o">.</span><span class="n">copy_from_system</span><span class="p">()</span>   <span class="c"># Retrieve from system clipboard.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">instance</span>
<span class="go">Clipboard(unicode=u&#39;asdf&#39;, text, oemtext, locale)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c"># The line above shows that *instance* now contains content for</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c">#  4 different clipboard formats: unicode, text, oemtext, locale.</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c">#  The unicode format content is also displayed.</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">instance</span><span class="o">.</span><span class="n">copy_to_system</span><span class="p">()</span>     <span class="c"># Transfer back to system clipboard.</span>
</pre></div>
<p>The situation frequently occurs that a developer would like to use the
Windows system clipboard to perform some task without the data currently
stored in it being lost.  This backing up and restoring can easily be
achieved as follows:</p>
<div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">dragonfly.windows.clipboard</span> <span class="kn">import</span> <span class="n">Clipboard</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c"># Initialize instance with system clipboard content.</span>
<span class="gp">... </span><span class="n">original</span> <span class="o">=</span> <span class="n">Clipboard</span><span class="p">(</span><span class="n">from_system</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">original</span>
<span class="go">Clipboard(unicode=u&#39;asdf&#39;, text, oemtext, locale)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c"># Use the system clipboard to do something.</span>
<span class="gp">... </span><span class="n">temporary</span> <span class="o">=</span> <span class="n">Clipboard</span><span class="p">({</span><span class="n">Clipboard</span><span class="o">.</span><span class="n">format_unicode</span><span class="p">:</span> <span class="s">u&quot;custom content&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">temporary</span>
<span class="go">Clipboard(unicode=u&#39;custom content&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">temporary</span><span class="o">.</span><span class="n">copy_to_system</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">dragonfly.all</span> <span class="kn">import</span> <span class="n">Key</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Key</span><span class="p">(</span><span class="s">&quot;c-v&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">execute</span><span class="p">()</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c"># Restore original system clipboard content.</span>
<span class="gp">... </span><span class="k">print</span> <span class="n">Clipboard</span><span class="p">(</span><span class="n">from_system</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="c"># Show system clipboard contents.</span>
<span class="go">Clipboard(unicode=u&#39;custom content&#39;, text, oemtext, locale)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">original</span><span class="o">.</span><span class="n">copy_to_system</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">Clipboard</span><span class="p">(</span><span class="n">from_system</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="c"># Show system clipboard contents.</span>
<span class="go">Clipboard(unicode=u&#39;asdf&#39;, text, oemtext, locale)</span>
</pre></div>
</div>
<div class="section" id="clipboard-class">
<h2>Clipboard class<a class="headerlink" href="#clipboard-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="dragonfly.windows.clipboard.Clipboard">
<!--[dragonfly.windows.clipboard.Clipboard]-->class <tt class="descname">Clipboard</tt><big>(</big><em>contents=None</em>, <em>text=None</em>, <em>from_system=False</em><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard" title="Permalink to this definition">¶</a></dt>
<dd><dl class="method">
<dt id="dragonfly.windows.clipboard.Clipboard.copy_from_system">
<!--[dragonfly.windows.clipboard.Clipboard.copy_from_system]--><tt class="descname">copy_from_system</tt><big>(</big><em>formats=None</em>, <em>clear=False</em><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.copy_from_system" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy the Windows system clipboard contents into this instance.</p>
<dl class="docutils">
<dt>Arguments:</dt>
<dd><ul class="first last simple">
<li><em>formats</em> (iterable, default: None) &#8211; if not None, only the
given content formats will be retrieved.  If None, all
available formats will be retrieved.</li>
<li><em>clear</em> (boolean, default: False) &#8211; if true, the Windows
system clipboard will be cleared after its contents have been
retrieved.</li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="dragonfly.windows.clipboard.Clipboard.copy_to_system">
<!--[dragonfly.windows.clipboard.Clipboard.copy_to_system]--><tt class="descname">copy_to_system</tt><big>(</big><em>clear=True</em><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.copy_to_system" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy the contents of this instance into the Windows system
clipboard.</p>
<dl class="docutils">
<dt>Arguments:</dt>
<dd><ul class="first last simple">
<li><em>clear</em> (boolean, default: True) &#8211; if true, the Windows
system clipboard will be cleared before this instance&#8217;s
contents are transferred.</li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="dragonfly.windows.clipboard.Clipboard.get_format">
<!--[dragonfly.windows.clipboard.Clipboard.get_format]--><tt class="descname">get_format</tt><big>(</big><em>format</em><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.get_format" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieved this instance&#8217;s content for the given <em>format</em>.</p>
<dl class="docutils">
<dt>Arguments:</dt>
<dd><ul class="first last simple">
<li><em>format</em> (int) &#8211; the clipboard format to retrieve.</li>
</ul>
</dd>
</dl>
<p>If the given <em>format</em> is not available, a <em>ValueError</em>
is raised.</p>
</dd></dl>

<dl class="attribute">
<dt id="dragonfly.windows.clipboard.Clipboard.get_system_text">
<!--[dragonfly.windows.clipboard.Clipboard.get_system_text]--><tt class="descname">get_system_text</tt><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.get_system_text" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="dragonfly.windows.clipboard.Clipboard.get_text">
<!--[dragonfly.windows.clipboard.Clipboard.get_text]--><tt class="descname">get_text</tt><big>(</big><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.get_text" title="Permalink to this definition">¶</a></dt>
<dd>Retrieve this instance&#8217;s text content.  If no text content
is available, this method returns <em>None</em>.</dd></dl>

<dl class="method">
<dt id="dragonfly.windows.clipboard.Clipboard.has_format">
<!--[dragonfly.windows.clipboard.Clipboard.has_format]--><tt class="descname">has_format</tt><big>(</big><em>format</em><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.has_format" title="Permalink to this definition">¶</a></dt>
<dd><p>Determine whether this instance has content for the given
<em>format</em>.</p>
<dl class="docutils">
<dt>Arguments:</dt>
<dd><ul class="first last simple">
<li><em>format</em> (int) &#8211; the clipboard format to look for.</li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="dragonfly.windows.clipboard.Clipboard.has_text">
<!--[dragonfly.windows.clipboard.Clipboard.has_text]--><tt class="descname">has_text</tt><big>(</big><big>)</big><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.has_text" title="Permalink to this definition">¶</a></dt>
<dd>Determine whether this instance has text content.</dd></dl>

<dl class="attribute">
<dt id="dragonfly.windows.clipboard.Clipboard.set_system_text">
<!--[dragonfly.windows.clipboard.Clipboard.set_system_text]--><tt class="descname">set_system_text</tt><a class="headerlink" href="#dragonfly.windows.clipboard.Clipboard.set_system_text" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">Clipboard toolkit</a><ul>
<li><a class="reference external" href="#usage-examples">Usage examples</a></li>
<li><a class="reference external" href="#clipboard-class">Clipboard class</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="windows.html" title="previous chapter">Windows sub-package</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="misc.html" title="next chapter">Miscellaneous</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/clipboard.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="misc.html" title="Miscellaneous"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="windows.html" title="Windows sub-package"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Dragonfly v0.6.4rc3 documentation</a> &raquo;</li>
          <li><a href="windows.html" accesskey="U">Windows sub-package</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Christo Butcher.
      Last updated on Feb 01, 2009.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>